Document differences per shell #3207
Conversation
theunrepentantgeek
requested review from
davefellows,
matthchr,
babbageclunk and
super-harsh
as code owners
theunrepentantgeek
added
the
documentation
There was a problem hiding this comment.
I'm not sold that having the ability to select shell for the options that are exactly the same is worth it.
For example, for
$ kubectl delete resourcegroups/aso-sample-rg
modulo the starting character, this command is identical on all shells. So I feel like we don't need to give users shell-selection for it? offering shell selection on these options adds a lot of boilerplate to this file (in terms of the markdown), and also adds a lot of clickable options that IMO end up distracting from the simplicity of the installation process in the rendered UI.
Could we consider one of the following options:
- Offer the shell selection only once, and then give all of the rest of the instructions inside of that selection? So the user just chooses their shell once at the top and is done, rather than having to pick it N times? This would reduce the amount of screen real-estate devoted to the shell choices and simplify the user options (pick once), though it might mean even more duplication in the actual markdown.
- Only offer shell selection where the cmd actually materially differs? (This would remove by my count ~8 or 9 selectors)
Note: I can't actually leave my comment on the _index.md file for some reason, having the same issue as @super-harsh was.
v2/README.md
Outdated
|
|
||
| > [!WARNING] | ||
| > If you `kubectl delete` an Azure resource from your cluster, ASO ***will*** delete the matching Azure resource. This can | ||
| > be dangerous if you were to do this with an existing resource group which contains resources you do not wish to be deleted.** |
There was a problem hiding this comment.
| > be dangerous if you were to do this with an existing resource group which contains resources you do not wish to be deleted.** | |
| > be dangerous if you were to do this with an existing resource group which contains resources you do not wish to be deleted. |
|
I've updated to remove tabs where the content is identical. I suspect GH is having trouble with the transformation from a soft-link to an actual file, and this is why comments on the file aren't available. |
|
On line 274, the events look old, would be good to update with how they look now currently |
Done. |
What this PR does / why we need it:
We've had users who encountered problems because they were using a different shell (not bash) and got tripped up by subtle differences in command-line syntax.
For example, bash requires
'single quotes'aroundcrdPatternto avoid expansion of any*wildcards, but if you include those same'quotes'when using cmd you end up with patterns that don't work.This PR splits our landing pages into different forms for GitHub vs our documentation site.
For GitHub, we include a warning about the examples being bash specific. For our documentation site, we show examples for each shell.
Closes #3145 by showing the different syntax for each shell on our documentation site.
Closes #3142 by showing how crdPattern works different for each shell
How does this PR make you feel:
If applicable: